home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / headers.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  17.2 KB  |  454 lines
  1. //=============================================================================
  2. // File:       headers.h
  3. // Contents:   Declarations for DwHeaders
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. //
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_HEADERS_H
  24. #define DW_HEADERS_H
  25.  
  26. #include <iostream>
  27. #include <vector>
  28.  
  29. #ifndef DW_CONFIG_H
  30. #include <mimelib/config.h>
  31. #endif
  32.  
  33. #ifndef DW_STRING_H
  34. #include <mimelib/string.h>
  35. #endif
  36.  
  37. #ifndef DW_MSGCMP_H
  38. #include <mimelib/msgcmp.h>
  39. #endif
  40.  
  41. #ifndef DW_ENTITY_H
  42. #include <mimelib/entity.h>
  43. #endif
  44.  
  45. #ifndef DW_MSGID_H
  46. #include <mimelib/msgid.h>
  47. #endif
  48.  
  49. #ifndef DW_MAILBOX_H
  50. #include <mimelib/mailbox.h>
  51. #endif
  52.  
  53. #ifndef DW_MEDIATYP_H
  54. #include <mimelib/mediatyp.h>
  55. #endif
  56.  
  57. #ifndef DW_DATETIME_H
  58. #include <mimelib/datetime.h>
  59. #endif
  60.  
  61. #ifndef DW_MECHANSM_H
  62. #include <mimelib/mechansm.h>
  63. #endif
  64.  
  65. #ifndef DW_DISPTYPE_H
  66. #include <mimelib/disptype.h>
  67. #endif
  68.  
  69. class DwMessage;
  70. class DwBodyPart;
  71. class DwField;
  72. class DwFieldBody;
  73. class DwDateTime;
  74. class DwMailboxList;
  75. class DwAddressList;
  76. class DwMediaType;
  77. class DwMechanism;
  78. class DwText;
  79.  
  80. //=============================================================================
  81. //+ Name DwHeaders -- Class representing the collection of header fields in a message or body part
  82. //+ Description
  83. //. {\tt DwHeaders} represents the collection of {\it header fields} (often
  84. //. called just {\it headers}) in an {\it entity} (either a message or body
  85. //. part), as described in RFC-822 and RFC-2045.  A {\tt DwHeaders} object
  86. //. manages a list of {\tt DwField} objects, which represent the individual
  87. //. header fields.
  88. //.
  89. //. In the tree (broken-down) representation of a message, a {\tt DwHeaders}
  90. //. object is an intermediate node, having both a parent node and several
  91. //. child nodes.  The parent node is the {\tt DwEntity} object that contains
  92. //. it.  The child nodes are the {\tt DwField} objects in the list it manages.
  93. //. (See the man page for {\tt DwMessageComponent} for a discussion of
  94. //. the tree representation of a message.)
  95. //.
  96. //. Normally, you do not create a {\tt DwHeaders} object directly, but you
  97. //. access it through the {\tt Headers()} member function of {\tt DwEntity},
  98. //. which creates the {\tt DwHeaders} object for you.
  99. //.
  100. //. While {\tt DwHeaders} has public member functions for managing the list
  101. //. of {\tt DwField} objects it contains, you will normally use convenience
  102. //. functions to access the field bodies of the header fields directly.
  103. //. You can access the field body for a specific well-known header field
  104. //. by using the member function {\tt <Field>()}, where {\tt <Field>} is
  105. //. the field name of the header field with hyphens removed and the first
  106. //. word following a hyphen capitalized.  For example, to access the field
  107. //. body for the "MIME-version" header field, use {\tt MimeVersion()}.
  108. //. The member function {\tt <Field>()} will create a header field with
  109. //. field name {\tt <Field>} if such a header field does not already exist.
  110. //. You can check for the existence of a particular well-known header field
  111. //. by using the member function {\tt Has<Field>()}.  For example, to check
  112. //. for the existence of the MIME-version header field, use
  113. //. {\tt HasMimeVersion()}.  Well-known header fields are those documented in
  114. //. RFC-822 (standard email), RFC-1036 (USENET messages), RFC-2045 (MIME
  115. //. messages), and possibly other RFCs.
  116. //.
  117. //. In the case of an extension field or user-defined field, you can access
  118. //. the field body of the header field by calling the member function
  119. //. {\tt FieldBody()} with the field name as its argument.  If the extension
  120. //. field or user-defined field does not exist, {\tt FieldBody()} will
  121. //. create it.  You can check for the existence of an extension field or
  122. //. user-defined field by using the member function {\tt HasField()} with
  123. //. the field name as its argument.
  124. //.
  125. //. {\tt DwHeaders} has several other member functions provided for the
  126. //. sake of completeness that are not required for most applications.
  127. //. These functions are documented below.
  128. //=============================================================================
  129. // Last updated 1997-08-26
  130. //+ Noentry ~DwHeaders sClassName CopyFields mFirstField _AddField
  131.  
  132.  
  133. class DW_EXPORT DwHeaders : public DwMessageComponent {
  134.  
  135. public:
  136.  
  137.     DwHeaders();
  138.     DwHeaders(const DwHeaders& aHeaders);
  139.     DwHeaders(const DwString& aStr, DwMessageComponent* aParent=0);
  140.     //. The first constructor is the default constructor, which sets the
  141.     //. {\tt DwHeaders} object's string representation to the empty string
  142.     //. and sets its parent to {\tt NULL}.
  143.     //.
  144.     //. The second constructor is the copy constructor, which performs a
  145.     //. deep copy of {\tt aHeaders}.
  146.     //. The parent of the new {\tt DwHeaders} object is set to {\tt NULL}.
  147.     //.
  148.     //. The third constructor copies {\tt aStr} to the {\tt DwHeaders}
  149.     //. object's string representation and sets {\tt aParent} as its parent.
  150.     //. The virtual member function {\tt Parse()} should be called immediately
  151.     //. after this constructor in order to parse the string representation.
  152.     //. Unless it is {\tt NULL}, {\tt aParent} should point to an object of a class
  153.     //. derived from {\tt DwEntity}.
  154.  
  155.     virtual ~DwHeaders();
  156.  
  157.     const DwHeaders& operator = (const DwHeaders& aHeaders);
  158.     //. This is the assignment operator, which performs a deep copy of
  159.     //. {\tt aHeaders}.  The parent node of the {\tt DwHeaders} object
  160.     //. is not changed.
  161.  
  162.     virtual void Parse();
  163.     //. This virtual function, inherited from {\tt DwMessageComponent},
  164.     //. executes the parse method for {\tt DwHeaders} objects.  The parse
  165.     //. method creates or updates the broken-down representation from the
  166.     //. string representation.  For {\tt DwHeaders} objects,
  167.     //. {\tt DwHeaders::Parse()} parses the string representation to create
  168.     //. a list of {\tt DwField} objects.  This member function also calls
  169.     //. the {\tt Parse()} member function of each {\tt DwField} object in
  170.     //. its list.
  171.     //.
  172.     //. You should call this member function after you set or modify the
  173.     //. string representation, and before you access any of the header fields.
  174.     //.
  175.     //. This function clears the is-modified flag.
  176.  
  177.     virtual void Assemble();
  178.     //. This virtual function, inherited from {\tt DwMessageComponent},
  179.     //. executes the assemble method for {\tt DwHeaders} objects.  The
  180.     //. assemble method creates or updates the string representation from
  181.     //. the broken-down representation.  That is, the assemble method
  182.     //. builds the string representation from its list of {\tt DwField}
  183.     //. objects.  Before it builds the string representation, this function
  184.     //. first calls the {\tt Assemble()} member function of each {\tt DwField}
  185.     //. object in its list.
  186.     //.
  187.     //. You should call this member function after you set or modify any
  188.     //. of the header fields, and before you retrieve the string
  189.     //. representation.
  190.     //.
  191.     //. This function clears the is-modified flag.
  192.  
  193.     virtual DwMessageComponent* Clone() const;
  194.     //. This virtual function, inherited from {\tt DwMessageComponent},
  195.     //. creates a new {\tt DwHeaders} on the free store that has the same
  196.     //. value as this {\tt DwHeaders} object.  The basic idea is that of
  197.     //. a virtual copy constructor.
  198.  
  199.     DwBool HasBcc() const;
  200.     DwBool HasCc() const;
  201.     DwBool HasComments() const;
  202.     DwBool HasDate() const;
  203.     DwBool HasEncrypted() const;
  204.     DwBool HasFrom() const;
  205.     DwBool HasInReplyTo() const;
  206.     DwBool HasKeywords() const;
  207.     DwBool HasMessageId() const;
  208.     DwBool HasReceived() const;
  209.     DwBool HasReferences() const;
  210.     DwBool HasReplyTo() const;
  211.     DwBool HasResentBcc() const;
  212.     DwBool HasResentCc() const;
  213.     DwBool HasResentDate() const;
  214.     DwBool HasResentFrom() const;
  215.     DwBool HasResentMessageId() const;
  216.     DwBool HasResentReplyTo() const;
  217.     DwBool HasResentSender() const;
  218.     DwBool HasResentTo() const;
  219.     DwBool HasReturnPath() const;
  220.     DwBool HasSender() const;
  221.     DwBool HasSubject() const;
  222.     DwBool HasTo() const;
  223.     // RFC-822 fields
  224.     //
  225.     DwBool HasApproved() const;
  226.     DwBool HasControl() const;
  227.     DwBool HasDistribution() const;
  228.     DwBool HasExpires() const;
  229.     DwBool HasFollowupTo() const;
  230.     DwBool HasLines() const;
  231.     DwBool HasNewsgroups() const;
  232.     DwBool HasOrganization() const;
  233.     DwBool HasPath() const;
  234.     DwBool HasSummary() const;
  235.     DwBool HasXref() const;
  236.     // RFC-1036 fields
  237.     //
  238.     DwBool HasContentDescription() const;
  239.     DwBool HasContentId() const;
  240.     DwBool HasContentTransferEncoding() const;
  241.     DwBool HasCte() const;
  242.     DwBool HasContentType() const;
  243.     DwBool HasMimeVersion() const;
  244.     // RFC-2045 fields
  245.     //
  246.     DwBool HasContentDisposition() const;
  247.     // RFC-1806
  248.     //
  249.     //. Each member function in this group returns a boolean value indicating
  250.     //. whether a particular well-known header field is present in this
  251.     //. object's collection of header fields.
  252.  
  253.     DwBool HasField(const char* aFieldName) const;
  254.     DwBool HasField(const DwString& aFieldName) const;
  255.     //. Returns true if the header field specified by {\tt aFieldName} is
  256.     //. present in this object's collection of header fields.  These member
  257.     //. functions are used for extension fields or user-defined fields.
  258.  
  259.     DwAddressList&  Bcc();
  260.     DwAddressList&  Cc();
  261.     DwText&         Comments();
  262.     DwDateTime&     Date();
  263.     DwText&         Encrypted();
  264.     DwMailboxList&  From();
  265.     DwText&         InReplyTo();
  266.     DwText&         Keywords();
  267.     DwMsgId&        MessageId();
  268.     DwText&         Received();
  269.     DwText&         References();
  270.     DwAddressList&  ReplyTo();
  271.     DwAddressList&  ResentBcc();
  272.     DwAddressList&  ResentCc();
  273.     DwDateTime&     ResentDate();
  274.     DwMailboxList&  ResentFrom();
  275.     DwMsgId&        ResentMessageId();
  276.     DwAddressList&  ResentReplyTo();
  277.     DwMailbox&      ResentSender();
  278.     DwAddressList&  ResentTo();
  279.     DwAddress&      ReturnPath();
  280.     DwMailbox&      Sender();
  281.     DwText&         Subject();
  282.     DwAddressList&  To();
  283.     // RFC-822 fields
  284.     //
  285.     DwText& Approved();
  286.     DwText& Control();
  287.     DwText& Distribution();
  288.     DwText& Expires();
  289.     DwText& FollowupTo();
  290.     DwText& Lines();
  291.     DwText& Newsgroups();
  292.     DwText& Organization();
  293.     DwText& Path();
  294.     DwText& Summary();
  295.     DwText& Xref();
  296.     // RFC-1036 fields (USENET messages)
  297.     //
  298.     DwText&         ContentDescription();
  299.     DwMsgId&        ContentId();
  300.     DwMechanism&    ContentTransferEncoding();
  301.     DwMechanism&    Cte();
  302.     DwMediaType&    ContentType();
  303.     DwText&         MimeVersion();
  304.     // RFC-2045 fields
  305.     //
  306.     DwDispositionType& ContentDisposition();
  307.     // RFC-1806 Content-Disposition field
  308.     //
  309.     //. Each member function in this group returns a reference to a
  310.     //. {\tt DwFieldBody} object for a particular header field.  If the
  311.     //. header field does not already exist, it is created.  Use the
  312.     //. corresponding {\tt Has<Field>()} function to test if the header
  313.     //. field already exists without creating it.
  314.  
  315.     DwFieldBody& FieldBody(const DwString& aFieldName);
  316.     //. Returns a reference to the {\tt DwFieldBody} object for a particular
  317.     //. header field with field name {\tt aFieldName}.  If the header field
  318.     //. does not already exist, it is created.  Use {\tt HasField()}
  319.     //. to test if the header field already exists without creating it.
  320.     //. This member function allows access to extension fields or
  321.     //. user-defined fields.
  322.  
  323.     std::vector<DwFieldBody*> AllFieldBodies(const DwString& aFieldName);
  324.     //. Returns a vector of pointers to the {\tt DwFieldBody} objects for
  325.     //. all header fields with field name {\tt aFieldName}.  If the header
  326.     //. field does not already exist, it is created.  Use {\tt HasField()}
  327.     //. to test if the header field already exists without creating it.
  328.     //. This member function allows access to extension fields or
  329.     //. user-defined fields.
  330.  
  331.     int NumFields() const;
  332.     //. Returns the number of {\tt DwField} objects contained by this
  333.     //. {\tt DwHeaders} object.
  334.  
  335.     DwField* FirstField() const;
  336.     //. Returns a pointer to the first {\tt DwField} object contained by
  337.     //. this {\tt DwHeaders} object.  Use this member function to begin an
  338.     //. iteration over the entire list of {\tt DwField} objects.
  339.     //. Continue the iteration by calling {\tt DwField::Next()} on each
  340.     //. {\tt DwField} object.
  341.  
  342.     DwField* FindField(const char* aFieldName) const;
  343.     DwField* FindField(const DwString& aFieldName) const;
  344.     //. Searches for a header field by its field name.  Returns {\tt NULL}
  345.     //. if the field is not found.  This is an {\it advanced} function:
  346.     //. most applications should use the {\tt <Field>()} or
  347.     //. {\tt Has<Field>()} family of functions.
  348.  
  349.     void AddOrReplaceField(DwField* aField);
  350.     //. Adds a {\tt DwField} object to the list.  If a header field with
  351.     //. the same field name already exists, it is replaced by the new
  352.     //. header field.
  353.     //.
  354.     //. {\tt DwHeaders} takes responsibility for deleting the added
  355.     //. {\tt DwField} object.
  356.     //.
  357.     //. This is an advanced function.  Consider using the member functions
  358.     //. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
  359.     //. and {\tt FieldBody()} to add header fields.
  360.  
  361.     void AddField(DwField* aField);
  362.     //. Adds a {\tt DwField} object to the list. If a header field with
  363.     //. the same field name already exists, it is {\it not} replaced;
  364.     //. thus, duplicate header fields may occur when using this member
  365.     //. function.  (This is what you want for some header fields, such as
  366.     //. the "Received" header field).
  367.     //.
  368.     //. {\tt DwHeaders} takes responsibility for deleting the added
  369.     //. {\tt DwField} object.
  370.     //.
  371.     //. This is an advanced function.  Consider using the member functions
  372.     //. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
  373.     //. and {\tt FieldBody()} for adding header fields.
  374.  
  375.     void AddFieldAt(int aPos, DwField* aField);
  376.     //. This member functions follows the semantics of {\tt AddField()}
  377.     //. except that {\tt aPos} specifies a position for adding the field.
  378.     //. A position of 1 indicates the beginning of the list.  A position of
  379.     //. 0 indicates the end of the list.
  380.     //.
  381.     //. This is an advanced function.  Consider using the member functions
  382.     //. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
  383.     //. and {\tt FieldBody()} for adding header fields.
  384.  
  385.     void RemoveField(DwField* aField);
  386.     //. Removes the {\tt DwField} object from the list.  The {\tt DwField}
  387.     //. object is not deleted.
  388.  
  389.     void DeleteAllFields();
  390.     //. Removes all {\tt DwField} objects from the list and deletes them.
  391.  
  392.     static DwHeaders* NewHeaders(const DwString& aStr,
  393.         DwMessageComponent* aParent);
  394.     //. Creates a new {\tt DwHeaders} object on the free store.
  395.     //. If the static data member {\tt sNewHeaders} is {\tt NULL},
  396.     //. this member function will create a new {\tt DwHeaders}
  397.     //. and return it.  Otherwise, {\tt NewHeaders()} will call
  398.     //. the user-supplied function pointed to by {\tt sNewHeaders},
  399.     //. which is assumed to return an object from a class derived from
  400.     //. {\tt DwHeaders}, and return that object.
  401.  
  402.     //+ Var sNewHeaders
  403.     static DwHeaders* (*sNewHeaders)(const DwString&, DwMessageComponent*);
  404.     //. If {\tt sNewHeaders} is not {\tt NULL}, it is assumed to point to a
  405.     //. user-supplied function that returns an object from a class derived from
  406.     //. {\tt DwHeaders}.
  407.  
  408. protected:
  409.  
  410.     void _AddField(DwField* aField);
  411.     //. Add field but don't set the is-modified flag
  412.  
  413.     DwField* mFirstField;
  414.     DwField* mLastField;
  415.  
  416. protected:
  417.  
  418.     static const char* const sClassName;
  419.  
  420.     void CopyFields(DwField* aFirst);
  421.  
  422. public:
  423.  
  424.     virtual void PrintDebugInfo(std::ostream& aStrm, int aDepth=0) const;
  425.     //. This virtual function, inherited from {\tt DwMessageComponent},
  426.     //. prints debugging information about this object to {\tt aStrm}.
  427.     //. It will also call {\tt PrintDebugInfo()} for any of its child
  428.     //. components down to a level of {\tt aDepth}.
  429.     //.
  430.     //. This member function is available only in the debug version of
  431.     //. the library.
  432.  
  433.     virtual void CheckInvariants() const;
  434.     //. Aborts if one of the invariants of the object fails.  Use this
  435.     //. member function to track down bugs.
  436.     //.
  437.     //. This member function is available only in the debug version of
  438.     //. the library.
  439.  
  440. private:
  441.  
  442.     void _PrintDebugInfo(std::ostream& aStrm) const;
  443.  
  444. };
  445.  
  446.  
  447. inline DwField* DwHeaders::FirstField() const
  448. {
  449.     return mFirstField;
  450. }
  451.  
  452. #endif
  453.  
  454.